ReadMe for the "What Time Is It?" Project
For Apple //e ProDOS 8
Written in Aztec C65 in the AppleX Cross-Development Environment
(C) Copyright Bill Buckels 1991-2008
All Rights Reserved.

BEFORE USING, YOU MUST READ AND AGREE TO THE DOCUMENT LICENCE.TXT
IN ITS ENTIRETY OR REMOVE ALL OF THIS FROM YOUR COMPUTER NOW.

DO NOT CHANGE ANY OF THIS UNLESS YOU HAVE A COMPLETE UNDERSTANDING 
OR IT MAY NOT WORK!

Overview

This project assumes that you have the AppleX environment installed and that
you are working within the Windows XP cmd window that the shortcut that comes
with AppleX provides.

I am not going to explain this further.

If you don't know what I'm talking about install AppleX available from my
Aztec C website at:

http://www.clipshop.ca/Aztec

This project is a complete build environment under AppleX for both the
English and French Versions of "What Time Is It?".

It does not contain the IBM Graphics and the intermediate files that were
used to build the finished graphics that are provided with this project. I'll
release all that separately if at all because that requires lots of
explanation that really isn't related directly to the programming of this. I
may already have done so by the time you are reading this.

In deciding to release this source code as a working project, I just felt
that to confuse an already complicated environment further by adding all
sorts of graphics processing would distract you from understanding how the
source code all gets put together into a program.

You can read the document "WhatTimeIsIt.txt" for the usual user-level drivel
or just run the program and read the source code to see how it works.

This project also comes with working french and english Apple II emulator
diskimages of the completed project for whatever diabolical amusement they
may provide.

Overlays

Since memory is not abundant on the Apple //e I have broken this project into
overlays. Overlays have always needed lots of fiddling because you need to
make sure that they remain as small as possible. Common routines used by all
overlays are stored in the main module. In this case, TIME.SYSTEM (time.c).

Routines specific to an overlay are stored in that overlay.

In this project, overlays are used in a couple or three ways. However, every
overlay in this project occupies exactly the same area of memory, and each is
called in its own turn from the main module TIME.SYSTEM (time.c).

CINIT.OVR and PLOGO.OVR are initialization overlays. The code they use is not
shared by the other modules. FLOGO.OVR is the french equivalent of PLOGO.OVR.

When "What Time Is It?" starts-up it calls these. All this is pretty-well
commented in TIME.C and further in the respective overlays' source code.

MAINMENU.OVR is a navigational overlay (a switchboard of sorts) and is called
after initialization from TIME.SYSTEM. But since there is no point in using
memory when a menu choice is selected, this overlay comes and goes as
required.

When a menu choice is selected from MAINMENU.OVR the corresponding overlay
for the menu choice is loaded.

TIME0.OVR, TIME1.OVR, and TIME2.OVR are the overlays for activities selected
from MAINMENU.OVR. Again, you can review the source code in time.c to see how
this all works.

Upon sucessful completion of the activities in TIME0.OVR, TIME1.OVR, and
TIME2.OVR a respective reward overlay is called; either TIME0A.OVR,
TIME1A.OVR, or TIME2A.OVR.

English and French Versions

As I said in the beginning, PLOGO.OVR and FLOGO.OVR are really the same
program with English or French being set respectively within each. This is
somewhat of a hack, and to see how the english and french versions are
actually built, the MAKEFILE should be reviewed in addition to the source for
for PLOGO and FLOGO.

Another difference between the English and French Versions is the image
libraries for each; TIME.RIB and FTIME.RIB. The only difference between these
two libraries is the screen for MAINMENU.OVR; TIME.RIB contains an English
screen and FTIME.RIB contains a French Screen.

The third (and final) difference is in the English and French title screens;
PLOG.RAG and FLOGO.RAG.

Again, the MAKEFILE should prove informative for further info as to exactly
what I do to build an English and French version of "What Time Is It?" by
substituting the 3 English artifacts mentioned above with their French
equivalents to build a French version.

All this hacking might seem a little inelegant, but it was all done for
various reasons, of which one was that the publisher did not want to provide
both versions on the same disk so there was no requirement to switch between
languages on the fly. Disk space was at a premium as well, as was memory so
not mixing the versions in the same executable program distribution kept the
disk size and memory usage to a reasonable minimum. So I hacked it this way,
and delivered it this way, and since the finished product all worked I moved
on.

So what you have here is an English program that is patched when it is built
to create a French Version with what I considered minimal effort at the time.

Auxilliary Memory

Perhaps the most valuable information in this project is how I use the upper
RAM bank on the Apple //e to store and retrieve my graphics. Reviewing this
source code and the G2 library source code that I provided with AppleX should
clarify how this is all done.

Clock Routines

My clock routines are done using a fairly sparse table driven methodology,
again in a an effort to run as quickly as possible with as little memory
usage as possible.

Exactly how this is done can be reviewed in the circlepoints routines that
are in any of the TIMEO, TIME1, and TIME2  modules. The reason this code is
repeated in each of those overlays goes back to saving memory by balancing
overlays with each other and in the main module. If the main module gets too
bulky then other overlays won't have room to run. I moved evrything around
until it all fit, adding code and removing code as required. This is the way
it ended-up working.

MAKEFILE, Directories, and DiskImages

I have arranged the build environment into a main directory and 3
subdirectories.

The MAKEFILE depends on these subdirectories as well as the AppleX build
environment which requires Windows XP.

The main directory contains all the source code and this ReadMe file and its
2 associated text files, and the MAKEFILE and nothing else.

The RES (resources) subdirectory is used in conjunction with the Makefile to
create the English and French Versions from scratch.

The ENGLISH and FRENCH subdirectories are the GOAL directories and a complete
version of the program is created in each of these in their respective
languages.

The ENGLISH and FRENCH subdirectories also contain working DiskImages of the
finished project. They also contain PRODOS 8 but no additional system files.

Compatibility

These programs have been used on real Apple //e's and Apple //e emulators in
Windows XP. They have also been tried and true back in their development
stage on Apple GS's and even on Macintoshes using the Apple //e emulators of
the day.

The Apple //e that I used to originally develop these on had a 5 MGHZ zip
chip which was an accelator that replaced the 6502 processor that ran at 1
MGHZ. With the zip chip, my Apple //e ran quite as quickly as my old true-
blue IBM-PC or so it almost seemed when it came to this sort of program.

Most importantly these programs all behaved well whether run in an emulator
or run in native mode.

So depite the fact that the code is a little messier than it would be if I
wrote it today, compatibility has never been an issue with these programs as
far as I know.

Final Comments

So what you have here is a real full-blown commercial program of the flavour
of the bygone Apple //e era complete with source code and some pretty fair
architecture for its day. It's not really very complicated either, once you
get into it, and if your were so inclined you could use this whole affair as
the basis for your own programs of a similar nature.

Since you are obviously reading this for some reason of interest, I do hope
that my notes and this project satisfy whatever perverse reason that finds
you playing with all this old stuff in the first place.

Have Fun!

Bill Buckels
bbuckels@mts.net
March 2008

(C) Copyright Bill Buckels 1991-2008
All Rights Reserved.

End of ReadMe
